The Order Search feature is intended for merchants to perform searches on a large number of Orders in a Project.
3 months are indexed and can be retrieved.- maintain a cache of Orders,
- compare version numbers to detect outdated Orders,
- detect if the search index for an Order is out of date and react accordingly (for example display a warning, or initiate an update of the Order search index).
Activation of the API
To activate the API for your Projects, choose one of the following options:
- using the Change Order Search Status update action on the Project API.
- contacting the Composable Commerce support team and provide the region, project key(s), and use case(s).
Automatic deactivation
Representations
OrderSearchRequest
query | The Order search query. |
sortArray of OrderSearchSorting | Controls how results to your query are sorted. If not provided, the results are sorted by relevance in descending order. |
limitInt | The maximum number of search results to be returned on one page. Default: 10Minimum: 0Maximum: 100 |
offsetInt | The number of search results to be skipped in the response for pagination. Default: 0Minimum: 0Maximum: 10000 |
{
"query": {
"and": [
{
"fullText": {
"field": "customLineItems.name",
"language": "en",
"value": "banana"
}
},
{
"filter": [
{
"exact": {
"field": "store.name",
"language": "en",
"value": "fruit_store"
}
}
]
}
]
},
"sort": [
{
"field": "customLineItems.name",
"language": "en",
"order": "desc"
}
],
"limit": 50,
"offset": 0
}OrderPagedSearchResponse
totalInt | Total number of results matching the query. |
offsetInt | Number of elements skipped. |
limitInt | Number of results requested. Minimum: 0Maximum: 100 |
hitsArray of Hit | Actual results. |
Hit
idString | Unique identifier of the Order. |
versionInt | Current version of the Order. |
relevanceFloat | The higher the value is, the more relevant the hit is for the search request. Minimum:0Maximum: 1 |
Search Orders
view_orders:{projectKey}regionString | Region in which the Project is hosted. |
projectKeyString | key of the Project. |
application/jsonapplication/jsonCheck if Order Search index exists
200 status if the index exists, or a 404 status otherwise.view_orders:{projectKey}regionString | Region in which the Project is hosted. |
projectKeyString | key of the Project. |
curl --head https://api.{region}.commercetools.com/{projectKey}/orders/search -i \
--header "Authorization: Bearer ${BEARER_TOKEN}"query FetchIndicesExists {
ordersIndicesExist {
searchableIndexExists
newInProgress
}
}
The query response contains the following fields indicating the status of the search index:
searchableIndexExists- the index exists and Orders can be searched.newInProgress- the index is being created by a job. Use thereIndexAllOrdersmutation to get the job ID.
FetchIndicesExists query to be executed as cURL command:$ curl -X POST https://api.{region}.commercetools.com/{projectKey}/orders/indexer/graphql \
-H "Content-Type:application/json" \
-H "Authorization:Bearer ..." \
-d '{"query": "{ ordersIndicesExist { searchableIndexExists } }" }'
Searchable Order fields
Number and date fields
| Standard field | Data type | Query for Orders |
|---|---|---|
completedAt | dateTime | completed at a certain date and time. |
createdAt | dateTime | created at a certain date and time. |
lastModifiedAt | dateTime | last modified at any of its fields at a certain date and time. |
version | long | with a certain version of the resource. |
customLineItems.state.quantity | long | with Custom Line Item's ItemState of a certain quantity. You may need to initiate an update to get the latest state of this field. |
lineItems.state.quantity | long | with Line Item's ItemState of a certain quantity. |
returnInfo.items.createdAt | dateTime | with ReturnItems created at a certain date and time. |
returnInfo.items.lastModifiedAt | dateTime | with ReturnItems last modified at a certain date and time. |
returnInfo.returnDate | dateTime | with ReturnInfo of a certain date and time. |
totalPrice.centAmount | long | with a total price of a certain amount. |
Phone fields
(783) 627-3740 will also match (783) 6273740.
The same applies to prefix queries.
Special characters are only taken into account when performing queries of type exact.| Standard field | Query for Orders with |
|---|---|
billingAddress.mobile | a billing address of a certain mobile number. |
billingAddress.phone | a billing address of a certain phone number. |
itemShippingAddresses.mobile | a Line Item shipping address of a certain mobile number. |
itemShippingAddresses.phone | a Line Item shipping address of a certain phone number. |
shippingAddress.mobile | a shipping address of a certain mobile number. |
shippingAddress.phone | a shipping address of a certain phone number. |
Text fields
| Standard field on Order | Query for Orders |
|---|---|
all | with a certain string in the combination of all fields. |
country | with a certain country. |
createdBy.clientId | created by an API Client with a certain client ID. |
customerEmail | with a certain Customer email address. |
customerGroup.key | from Customers of a certain Customer Group specified by its key.You may need to initiate an update to get the latest state of this field. |
customerGroup.name | from Customers of a certain Customer Group specified by its name.You may need to initiate an update to get the latest state of this field. |
lastModifiedBy.clientId | last modified by an API Client with a certain client ID. |
orderState | with a certain OrderState. |
paymentState | with a certain PaymentState. |
shipmentState | with a certain ShipmentState. |
state.name | with a State of a certain name for the language specified in the expression.You may need to initiate an update to get the latest state of this field. |
store.name | with a Store of a certain name for the language specified in the expression.You may need to initiate an update to get the latest state of this field. |
| Standard field on Billing Address | Query for Orders with a billing address of |
|---|---|
billingAddress.city | a certain city. |
billingAddress.company | a certain company. |
billingAddress.country | a certain country. |
billingAddress.firstName | a certain first name. |
billingAddress.lastName | a certain last name. |
billingAddress.postalCode | a certain post code. |
| Standard field on Item Shipping Address | Query for Orders with a Line Item Shipping address of |
|---|---|
itemShippingAddresses.city | a certain city. |
itemShippingAddresses.company | a certain company. |
itemShippingAddresses.country | a certain country. |
itemShippingAddresses.firstName | a certain first name. |
itemShippingAddresses.lastName | a certain last name. |
itemShippingAddresses.postalCode | a certain post code. |
| Standard field on Shipping Address | Query for Orders with a Shipping address of |
|---|---|
shippingAddress.city | a certain city. |
shippingAddress.company | a certain company. |
shippingAddress.country | a certain country. |
shippingAddress.firstName | a certain first name. |
shippingAddress.lastName | a certain last name. |
shippingAddress.postalCode | a certain post code. |
| Standard field on Line Items and Custom Line Items | Query for Orders with |
|---|---|
lineItems.productId | Line Items of a certain Product with a specified id. |
lineItems.variant.sku | Line Items of a certain Product Variant with a specified sku. |
lineItems.name | Line Items of a certain Product name for the language specified in the expression. |
lineItems.state.state.name | Line Items of a certain State name for the language specified in the expression.You may need to initiate an update to get the latest state of this field. |
customLineItems.name | Custom Line Items of a certain name for the language specified in the expression.You may need to initiate an update to get the latest state of this field. |
customLineItems.state.state.name | Custom Line Items of a certain State name for the language specified in the expression.You may need to initiate an update to get the latest state of this field. |
| Standard field on Payment, Return, or Shipping Info | Query for Orders with |
|---|---|
paymentInfo.payments.paymentMethodInfo.method | a certain payment method. You may need to initiate an update to get the latest state of this field. |
returnInfo.items.shipmentState | return items in a certain shipment state. |
returnInfo.items.paymentState | return items with a certain payment state. |
shippingInfo.shippingMethodName | a certain Shipping Method. |
Keyword fields
| Standard field on Order | Query for |
|---|---|
id | an Order with a specific id. |
orderNumber | an Order with a specific orderNumber. |
createdBy.anonymousId | Orders created by anonymous session with a specific ID. |
createdBy.externalUserId | Orders created by a Customer using external OAuth with a specific user ID. |
lastModifiedBy.anonymousId | Orders last modified by anonymous session with a specific ID. |
lastModifiedBy.externalUserId | Orders last modified by a Customer using external OAuth with a specific user ID. |
origin | Orders with a specific origin. |
customerGroup.id | Orders from Customers of a certain Customer Group specified by its id. |
customLineItems.state.state.key | Custom Line Items with a certain State specified by its key.You may need to initiate an update to get the latest state of this field. |
lineItems.state.state.key | Line Items with a certain State specified by its key.You may need to initiate an update to get the latest state of this field. |
paymentInfo.payments.interfaceId | a Payment of a certain interfaceId.You may need to initiate an update to get the latest state of this field. |
paymentInfo.payments.transactions.id | a Payment Transaction of a certain id.You may need to initiate an update to get the latest state of this field. |
paymentInfo.payments.transactions.interactionId | a Payment Transaction of a certain inferactionId.You may need to initiate an update to get the latest state of this field. |
returnInfo.returnTrackingId | a certain returnTrackingId on the ReturnInfo.You may need to initiate an update to get the latest state of this field. |
shippingInfo.deliveries.parcels.trackingData.trackingId | a certain trackingId on a Parcel's TrackingData.You may need to initiate an update to get the latest state of this field. |
state.key | Orders with a certain State specified by its key.You may need to initiate an update to get the latest state of this field. |
store.key | Orders with a certain Store specified by its key.You may need to initiate an update to get the latest state of this field. |
totalPrice.currencyCode | Orders with a total price of a certain CurrencyCode. |
Custom Fields
| Custom Field on Order, Payment, and Transaction | Query for Orders |
|---|---|
custom.<field-name> | with a Custom Field of a specific name. |
paymentInfo.payments.custom.<field-name> | with Payments with a Custom Field of a specific name.You may need to initiate an update to get the latest state of this field. |
paymentInfo.payments.transactions.custom.<field-name> | with Payment Transactions with a Custom Field of a specific name.You may need to initiate an update to get the latest state of this field. |
customType in simple expressions.CustomType
customType property on simple expressions indicating the data type of the field.BooleanType- For CustomFieldBooleanType Custom Fields.
StringType- For CustomFieldStringType Custom Fields.
LocalizedStringType- For CustomFieldLocalizedStringType Custom Fields.
EnumType- For CustomFieldEnumType Custom Fields.
LocalizedEnumType- For CustomFieldLocalizedEnumType Custom Fields.
NumberType- For CustomFieldNumberType Custom Fields.
DateType- For CustomFieldDateType Custom Fields.
TimeType- For CustomFieldTimeType Custom Fields.
DateTimeType- For CustomFieldDateTimeType Custom Fields.
SetType.StringType- For CustomFieldSetType of
StringTypeCustom Fields. SetType.LocalizedStringType- For CustomFieldSetType of
LocalizedStringTypeCustom Fields. SetType.EnumType- For CustomFieldSetType of
EnumTypeCustom Fields. SetType.LocalizedEnumType- For CustomFieldSetType of
LocalizedEnumTypeCustom Fields. SetType.NumberType- For CustomFieldSetType of
NumberTypeCustom Fields. SetType.DateType- For CustomFieldSetType of
DateTypeCustom Fields. SetType.TimeType- For CustomFieldSetType of
TimeTypeCustom Fields. SetType.DateTimeType- For CustomFieldSetType of
DateTimeTypeCustom Fields.
Query expression supported for which CustomType
SetType of the CustomType as for the individual CustomType itself.| CustomType | exact | fullText | prefix | range | wildcard | exists |
|---|---|---|---|---|---|---|
BooleanType | ✓ | ✓ | ||||
NumberType | ✓ | ✓ | ✓ | |||
StringType, EnumType, DateType, TimeType, DateTimeType | ✓ | ✓ | ✓ | ✓ | ✓ | |
LocalizedStringType, LocalizedEnumType | ✓ | ✓ | ✓ | ✓ | ✓ |
Examples
StringType Custom Field.{
"query": {
"exact": {
"field": "custom.myOrderField",
"value": "special order",
"customType": "StringType"
}
}
}
SetType of DateType Custom Field searching through all values for the Custom Field:{
"query": {
"exists": {
"field": "custom.myDateField",
"value": "2021-05-10",
"customType": "SetType.DateType"
}
}
}
Order Search Query
query field on OrderSearchRequest, as well as for the Advanced Order Search in the Merchant Center, are documented for multiple Search APIs on the Search query language page.
Search query language terms specific to Order Search are documented on this page.Simple expressions
field in simple expressions can have any of the searchable Order fields, like orderNumber, createdAt, country including fields of nested objects like LineItems (lineItems.productId) or ShippingMethods (shippingAddress.firstName).customType field must be used instead of the fieldType field that is documented for the generic search query language.Compound expressions
For example, this composition of two
and expressions is not supported: Z = (A and B and C),using only one
and expression, like: X = (A and B), is allowed.Using a different compound expression is allowed too, like for: Y = (A
and B or C).Z can still be specified by (X
and C) since X is a compound expression on a different level then.Example queries
fullText
name for any Custom Line Item in the Order.{
"query": {
"fullText": {
"field": "customLineItems.name",
"language": "en",
"value": "yellow car",
"mustMatch": "any"
}
}
}
exact
{
"query": {
"exact": {
"field": "lineItems.variant.sku",
"value": "chiquita_yellow_123",
"caseInsensitive": true
}
}
}
prefix
{
"query": {
"prefix": {
"field": "customerEmail",
"value": "commerceto",
"caseInsensitive": true
}
}
}
range
{
"query": {
"range": {
"field": "lastModifiedAt",
"gte": "2018-08-25T12:00:00.000Z",
"lte": "2018-08-26T12:00:00.000Z"
}
}
}
wildcard
{
"query": {
"wildcard": {
"field": "customerEmail",
"value": "ab*@commercetools.com"
}
}
}
{
"query": {
"wildcard": {
"field": "customerEmail",
"value": "ab?@commercetools.com",
"caseInsensitive": true
}
}
}
value. The email domain can be any as long as it ends with ".com".{
"query": {
"wildcard": {
"field": "customerEmail",
"value": "ab?@*.com",
"caseInsensitive": true
}
}
}
exists
customerEmail set:{
"query": {
"exists": {
"field": "customerEmail"
}
}
}
Compound expression AND
Example of a query with compound expression finding orders with a specific price:
{
"query": {
"and": [
{
"exact": {
"field": "totalPrice.currencyCode",
"value": "EUR"
}
},
{
"exact": {
"field": "totalPrice.centAmount",
"value": 2222
}
}
]
}
}
Compound expression OR with boost
butter in the lineItems.name field are scored as more relevant than those that have butter in their customLineItems.name field.{
"query": {
"or": [
{
"fullText": {
"field": "lineItems.name",
"language": "en",
"value": "butter",
"boost": 2
}
},
{
"fullText": {
"field": "customLineItems.name",
"language": "en",
"value": "butter"
}
}
]
}
}
Sorting
The following expression sorts the results ascending by the English Line Item name, but filtered on a specific Product ID:
{
"sort": [
{
"field": "lineItems.name",
"language": "en",
"order": "asc",
"filter": {
"exact": {
"field": "lineItems.productId",
"value": "4054a159-7f3e-4fe9-a30c-8db80ca7d665"
}
}
}
]
}
Note that you can only filter on the same parent field you sort by. In this case on the root of the Order.
Pagination
10 000 results by requesting them page by page.
The total field in a search query result indicates how many results match the search query in total.Limit
limit field allows you to set the maximum number of results returned on a page.
Any value between 0 and 100 is allowed, the default limit is 10.Offset
offset field allows you to control which page number you want to retrieve.
The default value is 0, meaning you retrieve the first page of query results containing as many results as specified by limit.
A value of 1 will skip the first page of results, and your result contains the second bucket of results with the specified limit.9 900 and 10 000 depending on the limit parameter.
That is, if you set the limit parameter to its maximum value of 100, the maximum offset is 9 900.
If you use the default page limit of 10, you can set the maximum offset value to 9 990.10 000 results in total, a higher offset would exceed that limit.
In such a case, the API responds with an error.Search Index updates
As the number of Orders in the Project grows over time and Order States change on the existing Orders, the Order Search index has to be kept in sync with the changes.
Automatic updates
Initiate update
Re-indexing can take several hours, depending on the volume of Orders.
Reindex mutation
manage_project_settings:{projectKey}, view_orders:{projectKey}mutation ReindexAllOrders {
reIndexAllOrders {
indexingJobId
existingIndexingJobId
}
}
This mutation returns following indexing job IDs:
indexingJobIdis the ID of a new indexing job.existingIndexingJobIdis the ID of an already running job making progress.
Check indexing progress
For each indexing job ID you can check the status of the respective jobs like so:
manage_project_settings:{projectKey}, view_orders:{projectKey}query GetReindexingStatus($jobId: String!) {
getReindexingStatus(id: $jobId) {
nbrOfIndexedDocuments
nbrOfFailedDocuments
totalNbrOfDocuments
percentCompleted
completed
}
}
Stop indexing jobs
You can stop the indexing of all Orders with following mutation:
manage_project_settings:{projectKey}mutation StopIndexingOrders {
stopOrdersIndexing {
status
}
}
status of the indexing job.GraphQL endpoint
You can access the GraphQL endpoint with following URL:
https://api.{region}.commercetools.com/{projectKey}/orders/indexer/graphql
The endpoint accepts HTTP POST requests with following fields in a JSON body:
query- String - GraphQL query as a stringvariables- Object - Optional - containing JSON object that defines variables for your queryoperationName- String - Optional - the name of the operation, in case you defined several of them in the query